Inside Macintosh: Programming With JManager /

Chapter 1 - Using JManager

Executing Java Applications

Most of the information in the previous sections describes how to load and execute Java applets, which are designed to be run within an embedding application. However, you can also execute Java applications, which can be launched just like any other application. To do so on the Mac OS, you must create a wrapper program around the Java application.

Note

You can also use the utility application JBindery to create a wrapper for Java applications. JBindery allows you to create standalone Java applications that you can launch just like any Mac OS application.

To launch a Java application using JManager, you must take the following steps:

1. Instantiate a Java runtime session.
2. Create an AWT context for the application.
3. Find the Java application's code.
4. Call the application's main method.

The first two steps are the same as for instantiating and executing a Java applet. However, finding and executing the Java application requires some interaction with the Java Runtime Interface (JRI). Listing 1-18 shows an example of finding and launching a Java application.

Listing 1-18 Launching a Java application

static Boolean initializeSampleApp()
{
   JRIEnv* env;
   JRIMethodID method;
   
   /* locate the application's code and add it to the class path */
   static const char* kSampleAppZipFile = "file:///$APPLICATION/
            AppSample.zip";
   FSSpec appSpec;
   if (JMURLToFSS(theSession, kSampleAppZipFile, &appSpec) != noErr)
      return false;
   
   if (JMAddToClassPath(theSession, &appSpec) != noErr)
       return false;
   
   /* next, use the JRI to locate the class */
   /* begin by getting a JRI_Env object */
   env = JMGetCurrentEnv(theSession);
   if (env == nil)
       return false;
    
   /* find the class--if it's in a package, separate with */
   /* slashes (/), for example, sun/awt/AppletViewer */
   theAppClass = JRI_FindClass(env, "AppSample");
   if (theAppClass == nil)
       return false;
   
   /* now find the method by name & signature */
   method = JRI_GetStaticMethodID(env, theAppClass, "main", 
         "([Ljava/lang/String;)V");
   if (method == nil)
       return false;
    
   /* request that the method be executed within the AWT context */
   /* note that there are no arguments to pass to this method */
   return noErr == JMExecStaticMethodInContext(theContext, theAppClass,
                       method, 0, nil);
}

In this example, the application's code is stored in a zip file. The location of the file is specified as a URL, and this is then converted to a file specification record using the JMURLToFSS function (page 93). The JMAddToClassPath function (page 94) adds this record to the class path so the Java runtime environment knows where to search for additional Java methods.

To find the class and main method of the Java application, you must use the Java Runtime Interface. Call the JManager function JMGetCurrentEnv (page 96) to get information about the JRI environment associated with this session, then call JRI functions to find the class and method. In Listing 1-18, the call to JRI_FindClass returns the class associated with the application appSample. The call JRI_GetStaticMethodID returns the ID of the main method in appSample (that is, the main routine). The JRI_GetStaticMethodID function requires that you pass the method's signature, which is a string that describes the method's parameters and return values. For a full description of the signature format, see the Java Runtime Interface documentation available at the Netscape Communications developer Web page:

http://developer.netscape.com/

Once you know the class and method ID, you can then call the JManager function JMExecStaticMethodInContext (page 69) to call the method and execute the application within the created AWT context. If the method requires any arguments, you pass them when you call JMExecStaticMethodInContext.

Note

Execution of the Java application is asynchronous. That is, execution of the application begins when the AWT context can devote time to doing so.

Although the launch process differs, Java applications rely on JManager to interact with the Mac OS in the same manner as applets do. Therefore, when writing your wrapper application, you must include frame callbacks and user-event handling routines just as you would for applets.

Since the Java program is an application, you cannot call a JManager function to exit. However, JManager automatically generates a Quit Application Apple event when the Java method java.lang.System.exit executes (that is, when the Java application quits). To respond to this event, you need to install an Apple event handler in your wrapper application. Listing 1-19 gives an example of using an event handler.

Listing 1-19 Using an Apple event handler to quit a Java application

static pascal OSErr _handleQUIT(AppleEvent* event, AppleEvent* reply,
   long refcon)
{
   theLoopContinues = false;
   return noErr;
}

void main(void) 
{
...
   AEInstallEventHandler(kCoreEventClass, kAEQuitApplication,
      NewAEEventHandlerProc(_handleQUIT), 0, false);

/* main event loop */
   while (theLoopContinues) {
      ...
      }
   JMCloseSession(theSession);
}

The Apple event handler _handleQUIT halts the main event loop; the wrapper application then ends the Java session and exits.

For more information about how to use Apple events, see Inside Macintosh: Interapplication Communication.